
/*
 * Copyright (C) 2008-2009 Archie L. Cobbs. All rights reserved.
 *
 * $Id: DatabaseUpdate.java 90 2009-04-23 03:07:07Z archie.cobbs $
 */

package org.dellroad.sidekar.datastore.updating;

import java.util.Set;

import org.dellroad.sidekar.datastore.Datastore;

/**
 * A Sidekar {@link Datastore} update managed by an {@link UpdatingDatastore}.
 *
 * <p>
 * {@link DatastoreUpdate}s modify a {@link Datastore} in some way, have unique names (within the scope of the database),
 * and have zero or more required predecessors.
 * </p>
 *
 * <p>
 * Once an update has been applied to a datastore, it must not be changed; otherwise, inconsistencies can exist between
 * datastores that were updated before the change vs. datastores that are updated after the change. If an update has been
 * used but had the wrong behavior, instead of changing the update, it's better to create a new update that depends on
 * the first as a predecessor and that corrects the mistake. Otherwise, you have to track down the datastores that were
 * incorrectly modified and fix them manually, so they end up in the same state that the new version of the update would
 * have left them in.
 * </p>
 */
public interface DatastoreUpdate {

    /**
     * Get the unique name of this update. This name must be unique among all
     * updates ever applied to the datastore and must never change once this
     * update has been applied to any datastore.
     *
     * @return the name of this update; must not be the empty string
     */
    String getName();

    /**
     * Get the names of the other updates (if any) that are required to be
     * performed before this update can be applied.
     *
     * @return set of zero or more names of other update names
     */
    Set<String> getRequiredPredecessors();

    /**
     * Update the given {@link Datastore} by modifying it in some way.
     *
     * @param datastore the {@link Datastore} to modify
     */
    void updateDatastore(Datastore datastore);
}

